Copyright: Copyright PC HELP-LINE, 1994


Contents
VB/Rig™

The "bullet-proofing" tool for serious developers.™

 Contents

Introduction

What is VB/Rig ?

Features

Components

Quick Start

Product Support and Licensing

Using VB/Rig

Defining Module Naming Conventions

Using Skip Tags

Rigging an Application

Limitations

Unclassified Details

Monitoring the Procedure Stack

Backup Procedures


 What is VB/Rig ?

Visual Basic has often been criticized for its decentralized approach to error-handling.  In an environment where potential runtime errors lurk behind nearly every line of code, "bullet-proofing" a VB application is a tedious, redundant, and, unfortunately, absolutely necessary chore that all serious developers face.

VB/Rig was conceived as an automated solution to the task of "rigging" an application for error-handling, and as a unique debugging tool for both developers and end-users.  It is probably best described as a specialized code-generator, capable of inserting a complete error-handling subsystem into your VB application.

______________

If you've programmed in Visual Basic for any length of time, you already know that VB's default response to any runtime error is to simply popup a terse message box, and then stop your application dead in its tracks.  Did you have some files open?  Were you in the middle of a database update?  Will the end-user wonder where the HECK his application suddenly disappeared to?

Yes, yes, and a great big definite YES!

VB, on the other hand, couldn't care less about what you were doing just before that little runtime error cropped up.  Your application is kaput.  History.  Terminated without mercy, and without pity by the VB runtime system.

To defend itself, your VB application needs to implement error-handling routines that make judicious use of the "On Error" statement.  Unfortunately, it's often difficult or impossible to anticipate every potential runtime error that might occur in your application.

Rather than write error-handlers only for those parts of your program where you're expecting errors to occur, what you really need is a "bumper-to-bumper" scheme that can handle even the unexpected errors.

______________

One of your goals as a serious developer is to design applications that cannot fail unexpectedly.  If you're a VB programmer, that means you must write a separate and unique error-handler for, at minimum, every event-procedure in every .FRM module of your project.  And for complete control and accuracy in dealing with errors, you really should write an error-handler for every non-trivial procedure in your application.

The sheer monotony of writing dozens (or perhaps hundreds) of nearly-identical error-handling routines, not to mention the time involved, has provided VB programmers with a convenient excuse for not implementing comprehensive error-handling schemes: "It's too tedious to do, and it takes too long."

Well, no longer -- VB/Rig can do it all for you automatically, painlessly, consistently, and effectively.

______________

VB/Rig's mission is to make runtime error-handling so easy to implement that you'll do it every time, all the time, as part of your normal development.


 Features

Standard Edition

"Rig" an entire VB application for error-handling with a few mouse-clicks.  VB/Rig gives you selective control over each module in your project.

Program logic is not altered or disturbed in any way.  VB/Rig inserts error-handling routines around your existing code, and frames it with conspicuous comments.  The comment frames also enable VB/Rig to completely remove the error-handling subsystem when desired, restoring the source code to its original state.

A complete application "procedure stack" is maintained at runtime.  This enables the error-handling subsystem to identify both the procedure in which the runtime error occurred, and the procedure in which it was actually handled, or trapped.  A valuable debugging feature in its own right, the procedure stack can be displayed in the Debug window as the application is running, or routed to the printer or a file for later examination.

The error-handling subsystem can popup a modal form whenever a runtime error occurs.  The form can display VB's built-in error explanations, or custom error messages that you provide.  The procedure stack is also displayed, with the "origin" and "trap" procedures highlighted.

Build a skeleton "Select Case" block in the error-handler of each rigged procedure.  This is a handy time-saver when you need to write custom code to handle certain kinds of errors.

VB/Rig can be directed to skip over any procedure that you don't want to disturb, simply by placing a specially formatted comment line, or "tag", at the top of the procedure.  You can use this feature to "lock-in" rigging that you've customized, or protect specialized error-handling code that you've written yourself.

Modules can be rigged and unrigged multiple times without ill effect.  If you add a new procedure to a module that has already been rigged, simply rig the entire module again to pickup the new routine.  Procedures that have already been rigged are skipped automatically.

VB/Rig is implemented totally in native VB code, so it integrates seamlessly into your application. Simply add the two provided VB modules to your project (one form and one code module), and compile them along with the rest of your code.  There are no additional .VBXs or .DLLs to ship, and no licensing fees.

VB/Rig requires that all your forms and code modules be saved "As Text".

VB/Rig always makes a backup copy of each module before rigging is inserted or removed.

Professional Edition (in addition to the Standard features)

Rig your entire application, or just a part of it.  You have total, selective control over each procedure in your project, and the level of rigging applied.

Runtime errors can be time-stamped and logged to a sequential file to help document and solve problems "in-the-field".  Log records contain all available information on the error, including a snapshot of the procedure stack, and the names of the procedures where the error occurred and where it was trapped.

Error-handling routines can be enabled or disabled at runtime, if desired.


 Components

The VB/Rig "Rigger"

VBRIG.EXE	The tool you use to insert or remove the error-handling subsystem from your application's source code.

VBRIG.HLP	VB/Rig's on-line documentation.  (this file)

VBRIG.INI	You must define your module naming conventions before you can use VB/Rig.

Your Applications

VBRIGxxx.FRM	This module provides a popup error window.  It must be added to each rigged application.

VBRIGxxx.BAS	This module provides the procedures needed to support the error-handling subsystem.  It must be added to each application.

WIN.INI	To fully enable VB/Rig's capability of logging runtime errors to a file, you must add a new section, and provide filenames for each application's log.  (Professional Edition only)


 Quick Start

Note:	You may find it helpful to experiment with the DEMOxxx projects provided with VB/Rig, before rigging one of your own applications.

1.	If you already have some custom error-handlers in your application, you may want to tag those procedures so that VB/Rig does not disturb your existing code.  To force VB/Rig to skip over a specific procedure, insert a Skip Tag as the very first line of code.

After tagging all the procedures to be skipped, unload your project from the VB editor, or close down VB.

2.	Run VB/Rig.  The Project Window is displayed.

3.	Click "Open Project..." and select the .MAK file for the VB project you want to rig. Modules that have their "read-only" attributes set will not be processed by VB/Rig, and will appear with a "(RO)" prefix.  Likewise, non-text modules will also be ignored, and will appear with an "(XT)" prefix.

4.	Manually select the modules you want to rig, or use the Quick Select Buttons located below the module list.  Unless you have a good reason to skip one, you should generally rig all the modules in your project.

5.	Click "Insert...".  The Rig Setup Window is displayed, showing the available options.  For this initial test, make sure the Trap Options are set to "Full", and check the Master Setup box.

6.	Click "OK".  VB/Rig will begin processing your application.

The amount of time it takes to rig an application depends on the number and size of the procedures in the project.  When rigging has been completed you can close VB/Rig, or minimize it and set it aside.

7.	Run VB, and open the project you rigged in Step 6.

8.	Add the provided VBRIGxxx.FRM and VBRIGxxx.BAS modules to your project, using the "File/Add File..." menu option.

9.	To test the error-handling subsystem you'll need to do something in your application that will cause a runtime error.  A simple option is to insert an "Error nn" statement somewhere in your code; this will force an error condition and trigger the runtime error trap.

10.	Run your application. When the runtime error occurs, a "VB/Rig" window will popup with an explanation of the error, including the current state of the procedure stack.  Note the procedure where the error occurred, and where it was trapped.

11.	Click "Close".  The "VB/Rig" window is dismissed, and your application will continue to run.


 Rigging an Application

Adding VB/Rig's error-handling features to your application requires two simple steps:

1.	Use the "rigger" utility, VBRIG.EXE, to enhance your source code.  This process inserts an error-handler into each procedure in your application, and frames it with conspicuous, specially-formatted comments.

2.	Add the two VB/Rig support modules, VBRIGxxx.FRM and VBRIGxxx.BAS, to your project.

The "Rigger" Utility

The first thing you see when you run VBRIG.EXE is the Project Window.  This is where you open your VB project, and select the modules you wish to rig.  The following controls are provided:

Module List

Quick Select Buttons

In general, you should rig every module in your application, but you may have specific reasons for leaving certain modules unmodified.  VB/Rig will not allow you to process modules that have their "read-only" attribute set, even though they may be part of your project.

After selecting the appropriate modules, begin rigging the project by clicking the "Insert..." (or "Delete...") button, or selecting the corresponding menu item.  VB/Rig processes each module, in turn, and continuously updates the progress meter as it works.

Before processing each module, VB/Rig presents the Rig Setup Window so you can setup the desired rigging options.  The following settings/controls are provided:

Procedure List

Quick Select Buttons

Trap Options

Code Options

Master Setup

You can setup different options for each module (Professional Edition only), or use the same options all the way through by checking the Master Setup box.

As a precaution, VB/Rig makes a backup copy of each module, before applying your rig options.

Working With "Rigged" Code

Once VB/Rig has updated your source code, and you have added the two support modules to your project, you can continue to develop and test your application inside VB, just as you did before.

You may wish to customize some of the default error-handlers, especially in those procedures where you know runtime errors are likely to occur.  File I/O, database access, and DDE/OLE links are three of the most common areas where custom error-handling is often needed.

If you do customize VB/Rig's default routines, you may also want to mark those procedures with a skip tag to protect them from subsequent rigging operations.

If you add new procedures to your project, you can simply re-rig the necessary modules with the same options you used the first time.  VB/Rig will add code only to the new procedures, and skip the ones that have already been rigged.

You should never modify or remove the special comments that VB/Rig uses to frame the error-handling routines.  The "rigger" utility uses these comments as control points when inserting or removing code.


 Limitations

VB/Rig strives to be as unintrusive to your application as possible, and will not modify existing code.  This "hands-off" approach, however, does create a few special situations that you need to be aware of:

1.	VB/Rig cannot dynamically re-write existing error-handling routines to change the rig options that were implemented.  In order to rig with different Trap Options or Code Options, you must first remove the existing rigging, then insert new rigging with the desired options.

You can, however, re-process existing rigging in order to seek-out and rig new "Exit" statements that were not present in the code the last time it was rigged.  In order to keep the procedure stack in sync, it is vitally important that procedure exit points be properly rigged.

2.	VB/Rig will not attempt to rig "Exit" statements that are part of an in-line "If" statement or a multi-instruction statement.  For example, VB/Rig will not properly rig these statements:

If MyFlag = True Then Exit Sub

- or -

MyReturnCode = 0 : Exit Function

In order to properly rig your application, you must re-code these statements so that only one instruction appears on each statement:

If MyFlag = True Then

      Exit Sub

End If

- and -

MyReturnCode = 0

Exit Function


 Defining Module Naming Conventions

Before you can rig any source module, you must list the file extension in the [extensions] section of your VBRIG.INI file.  Defining your naming conventions in this way accomplishes two things.  First, it identifies the entries in your project's .MAK file that are significant to VB/Rig (i.e. your source code).  Second, it forces you to setup additional naming conventions for VB/Rig to use during its Backup Procedures.

The general form of the [extensions] entries is:

original_ext=backup_ext,module_type

For example:

-- VBRIG.INI --

[extensions]

frm=fr~,form

bas=ba~,code

glo=glx,code

cmn=cm$,form

The value on the left side of the equal sign defines a valid extension that you wish VB/Rig to recognize.  The value immediately to the right of the equal sign is the extension VB/Rig will use when it makes a backup copy of the module.  Make certain that all your backup extensions are unique.

Following the backup extension, you should specify the module type as either "form" or "code".  VB/Rig processes form modules and code modules in slightly different ways, and it needs to know the module type when processing an unfamiliar extension.  If you do not state the module type for extensions other than  .FRM, VB/Rig will process them as "code" modules.

Note that the module types for .FRM and .BAS extensions cannot be overridden, and will always be processed as "form" and "code",  respectively.

VBRIG.INI must be present in the same directory as VBRIG.EXE.


 Using Skip Tags

To force VB/Rig to skip over a specific procedure without rigging it, insert the following comment as the very first line of code, after the "Sub procedure_name" statement.  For example:

Sub Command1_Click ()

'+++ VB/Rig Skip +++

Skip Tags are provided so you can "lock out" those procedures where you don't want existing error-handling code to be disturbed, and for any other situation where you want VB/Rig to simply leave a particular procedure alone.

Skip Tags protect the procedure from both the insertion, and the removal, of rigging.  If you ever manually enhance the error-handling code in a procedure that has already been rigged, it might be wise to insert a Skip Tag.  That way, you cannot accidentally remove the customized code.


 Monitoring the Procedure Stack

To display the procedure stack in the Debug window while your application is running, uncomment the "Debug.Print" statement in the priVBRig_MonitorStack procedure of the VBRIGxxx.BAS module.

The priVBRig_MonitorStack procedure can also function as a simple profiler.  You may want to consider modifying the code so that the data is written to a file, rather than the Debug window.  You could then examine the data, off-line, to identify the most time-consuming code, the most-executed code, etc.


 Backup Procedures

VB/Rig always makes a backup copy of a module, before rigging it.  The backup sequence used by VB/Rig work like this:

1.	If a previous backup file is present, it is deleted.

2.	The current version of the module is renamed, using the extension specified in the [extensions] section of the VBRIG.INI file.  (See Defining Module Naming Conventions)

3.	A new version of the module is created, using the original name.


 Module List

The Module List shows you which modules in the project are available for rigging, and allows you to select the ones you wish to process.  VB/Rig automatically screens out VBRIGxxx.FRM and VBRIGxxx.BAS if they are present, as well as any .VBX files and other non-source code elements.

In fact, a given module appears in the list only if its file extension (".BAS" or ".FRM", for example) is listed in the [extensions] section of your VBRIG.INI file.  (See Defining Module Naming Conventions)

It's also possible that a module will appear in the list, yet not be selectable for rigging.  In this case, VB/Rig will prefix the module name with an error code:

(ER)	A file error occurred.  VB/Rig could not open or read the file.

(RO)	The module has its "Read-Only" file attribute set.

(XT)	The module does not contain plain ASCII text.  The module may have been saved in VB's proprietary, binary format.  You must save the module "As Text" before VB/Rig can process it.


 Procedure List

The Procedure List shows you which procedures within the module will be rigged, and the level of rigging that will be applied to each procedure.

The second column shows the procedure name.  The first column shows the rig level, and has five possible states:

None	The procedure will not be rigged (if you are preparing to "Insert" rigging), or the procedure is not currently rigged (if you are preparing to "Remove" rigging).

Minimal	The procedure will be minimally rigged.  (See Trap Options)

Full	The procedure will be fully rigged.  (See Trap Options)

Rigged	The procedure is already rigged.

Skipped	The procedure contains a Skip Tag.

"Custom" Trap Options

If you select one of the three pre-defined Trap Options ("Full", "Minimal", or "Profiling"), the Procedure List is setup automatically and is not directly modifiable.  If you select "Custom" Trap Options, though, the list is enabled and you can customize it as needed.

You can manually select or deselect individual procedures using the mouse or the keyboard, or you can use the Quick Select Buttons to select a range of procedures.

You may also change the rig level of a procedure to one of three possible states: "None", "Minimal", or "Full".  To progressively cycle through each state:

1)	Hold down the CTRL key and click the procedure with the mouse.

- or -

2)	Set focus on the procedure using the cursor keys, then hold down the CTRL key and press ENTER.

Note:	Only the selected procedures will be rigged.  Setting a custom rig level on a deselected procedure has no effect, since the procedure will not be rigged.  Similarly, a rig level of "None" on a selected procedure also has no effect.


 Quick Select Buttons

These buttons provide shortcuts for selecting and deselecting items in the Module List and the Procedure List.  (Professional Edition only)

All

Selects all items in the list.

None

Deselects all items in the list

.BAS / .FRM

Selects all modules with a .BAS extension or .FRM extension, respectively.  (Module List only)

Match Wildcard

Toggles the current selection state of every item that matches the wildcard pattern provided in the accompanying combo box.  You can use one of the pre-defined patterns, or make up your own.

This matching capability is based on VB's Like operator.  You may want to review VB's on-line help for more detailed examples of the kind of patterns supported.  (Procedure List only)


 Trap Options

The following options control the degree, or level, of rigging that's inserted into your application.

Full

Full rigging inserts error-handling into every procedure of every module.  This is the most robust rigging scheme, and ensures that all errors are trapped locally, in the procedure where they actually occur.

If you do not plan to enhance the error-handling code that VB/Rig inserts, so that your application can actually respond to errors locally and attempt to correct them, Full rigging offers little advantage over Minimal rigging.

Minimal

Minimal rigging inserts error-handling only into the top-level, event procedures of your form modules, and into Sub Main if that procedure is present.  This is the minimum rigging required to protect your application from unanticipated runtime error faults.

If you have a solid grasp of how VB error-handling works, and are confident that you can identify the procedures in your code where runtime errors are most likely to occur, Minimal rigging is probably the best balance of functionality, code size, and performance.  One approach would be to insert Minimal rigging into the entire application, and then go back and re-rig selected non-event procedures with Full rigging.

Profiling  (Professional Edition only)

Profiling does not insert any error-handling code into your application, but it still allows you to monitor the Procedure Stack as your program runs.

This option would only be useful for internal testing.  Since runtime errors are not trapped, there would be no end-user benefit in shipping an application rigged only for Profiling.  (See Trap Options, "Log Errors to File")

Custom  (Professional Edition only)

The Custom option gives you procedure-level control over how each module is rigged.  Using the Procedure List, you can individually select which procedures are to be rigged, and the level of rigging that should be applied to each one.

Selecting Custom rigging disables the Master Setup feature, since a custom setup is specific to a particular module and cannot be applied globally to an entire project.


 Code Options

The following options control the functionality of the error-handling code that's inserted into your application.

Build SELECT CASE Blocks

A skeleton "Select Case" block is built into the error-handler of each rigged procedure.

This is a welcome time-saver if you plan to enhance VB/Rig's basic error-handling with your own custom code.

Popup Error Window

A popup window is displayed whenever a runtime error is trapped.

This window shows the error number, the error message (either VB's or a custom message provided by you), and the state of the Procedure Stack at the time the error was trapped.

Log Errors to File  (Professional Edition only)

A record is written to a log file whenever a runtime error is trapped.

The log is a simple comma-delimited file.  Each record contains the same information as the popup window, plus a time-stamp.  To completely enable this feature, you must also make the following modifications to your WIN.INI file:

1.	Create a new section header in WIN.INI called [vb/rig].

2.	Within this section, create one entry for each rigged application in the form of:

app.title=filespec

For example, if the App.Title property of your VB application is "CALC", WIN.INI might look like this:

-- WIN.INI --

[vb/rig]

calc=c:\temp\calc.log

All log records generated by CALC will now be written to C:\TEMP\CALC.LOG.

Enable/Disable Traps at Runtime  (Professional Edition only)

All "On Error" statements are enclosed by an "If" test that can be manipulated at runtime.

The global variable VBRigTrapsEnabled is used to enable or disable the error traps.  To enable error trapping, set VBRigTrapsEnabled equal to True; to disable error trapping, set it equal to False.  The default value is False.

This option provides flexibility because you can rig the application, but disable the traps so that runtime errors still terminate on the offending line of code.  When you're ready to ship, you can simply hard-code "VBRigTrapsEnabled = True" at the top of your program, or implement an .INI or command-line switch for the end-user to set.


Master Setup

 Master Setup  (Professional Edition only)

Check this box if you want to rig all the modules in your project with the same Trap Options and Code Options.

By default, VB/Rig prompts you to setup individual rig options for every module in your project.  If you don't need that level of customization, simply setup your rig options for the first module, and check "Master Setup".

Master Setup is not available if you select "Custom" Trap Options.


 Product Support and Licensing

PC HELP-LINE

35250 Silver Leaf Circle

Yucaipa, CA  92399

United States

Sales/Technical Support Hours

Internet:	72357.3523@compuserve.com

Voice:	909-797-3091

Mon-Fri  6pm - 10pm, Pacific Time

Sat-Sun  10am - 2pm, Pacific Time

Fax:	909-797-3091, 24hrs

Licensing

If you have purchased a single-user license for VB/Rig, you may install the software on as many computers as is necessary, for your own use.  However, your copy of the software must never be in-use on more than one computer at a time, and you may not share a license with someone else.

Important:	Under the terms of your license, you are not permitted to re-distribute the VB/Rig modules (VBRIGxxx.FRM, VBRIGxxx.BAS) as source code, either in their original form or in modified form.

Site licenses and corporate licenses are welcome and available; see ORDERFRM.DOC for details.  If you have special needs, let us know; we're easy.